home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / AIncludes / DeviceNotify.a < prev    next >
Text File  |  1996-05-01  |  9KB  |  252 lines
  1. ;
  2. ;    File:        DeviceNotify.a
  3. ;
  4. ;    Contains:    xxx put contents here xxx
  5. ;
  6. ;    Version:    Technology:    xxx put the technology version here xxx
  7. ;                Release:    Universal Interfaces 3.0d3 on Copland DR1
  8. ;
  9. ;    Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10. ;
  11. ;    Bugs?:        If you find a problem with this file, send the file and version
  12. ;                information (from above) and the problem description to:
  13. ;
  14. ;                    Internet:    apple.bugs@applelink.apple.com
  15. ;                    AppleLink:    APPLE.BUGS
  16. ;
  17. ;
  18.     IF &TYPE('__DEVICENOTIFY__') = 'UNDEFINED' THEN
  19. __DEVICENOTIFY__ SET 1
  20.  
  21.     IF &TYPE('__TYPES__') = 'UNDEFINED' THEN
  22.     include 'Types.a'
  23.     ENDIF
  24.     IF &TYPE('__KERNEL__') = 'UNDEFINED' THEN
  25.     include 'Kernel.a'
  26.     ENDIF
  27.     IF &TYPE('__NAMEREGISTRY__') = 'UNDEFINED' THEN
  28.     include 'NameRegistry.a'
  29.     ENDIF
  30.     IF FOR_SYSTEM8_PREEMPTIVE THEN
  31. ;
  32. ; ß
  33. ;##############################################################################
  34. ;    
  35. ;    File Name: DeviceNotifyPriv.h
  36. ;    
  37. ;    Description:
  38. ;                            The device notification service is used by Copland Kernel band
  39. ;                    Low level family expert code to inform high level "consumers" about
  40. ;                hot plugging/un-plugging of devices.
  41. ;                
  42. ;                The High level families or code modules running in priviledged mode 
  43. ;                can subscribe to the service with the DevNRegisterInterestIn().
  44. ;                LL Family notifies its consumers through the DevNNotifyThatThisChanged().
  45. ;    
  46. ;##############################################################################
  47. ;############################
  48. ; Defines
  49. ;############################
  50. ;
  51. ; typedef UInt32                         DevNRef
  52.  
  53. ;
  54. ;     a connection Reference Num for a particular subscription
  55. ;                                        a consumer subscription is identified by a unique
  56. ;                                         DevNSubRef. In order to cancel a consumer registration,
  57. ;                                        the DevNSubRef must be specified.
  58. ;                                    
  59. ;                                        a  Reference Num for a particular notification
  60. ;                                        A notification is identified by a unique DevNRef,
  61. ;                                        since a notification can go through couple of states, and 
  62. ;                                        it needs to be tracked with a unique identifier.
  63. ;                                    
  64. ;
  65. ;
  66. ; ß
  67. ;########################################################################
  68. ;    Known & valid Service Category definitions are defined in DFM.h
  69. ;########################################################################
  70. ;
  71.  
  72. kDevNAllServiceCategories        EQU        $FFFFFFFF            ; an option to subscribe to ALL valid service catagories
  73.  
  74. kMaxNumServiceCategories        EQU        20                    ; ***†should be in DFM.h ***
  75. ;
  76. ; ß
  77. ;########################################################################
  78. ; Event definition:
  79. ;    If kDevNSoftRequestMask is set in conjunction with an event value,
  80. ;    then a soft request is indicated, and the DevN will handle all the
  81. ;    drudgery associated with two-way transactions, etc.
  82. ;    (e.g. If (kDevNRemoved and kDevNSoftRequestMask) is received, it's 
  83. ;    a soft eject request)
  84. ;    If kDevNSoftRequestMask is NOT set, then it's a hard request
  85. ;     If the kDevNWarningMask is set, then it's an event warning that 
  86. ;    a given event is about to happen (and the consumer can't do a thing
  87. ;    about it). It will be followed later on by a gone hard event.
  88. ;    the kDevNWarningMask and the kDevNSoftRequestMask can NOT be set at
  89. ;    the same time.
  90. ;########################################################################
  91. ;
  92. ; typedef UInt32                         DevNEventType
  93.  
  94. ;
  95. ; pre-defined event mask
  96. ; ß
  97. ; definition of valid global event
  98. ; (10/11/95) Events are now enum instead of masks
  99. ; enum for "unsigned" values
  100. ;
  101.  
  102. kDevNSoftRequestMask            EQU        $80000000            ; bit indicating soft request
  103. kDevNWarningMask                EQU        $40000000            ; bit indicating a warning request
  104. kDevNAdded                        EQU        0                    ; New device/media/bus available
  105. kDevNRemoved                    EQU        1                    ; Existing device/media/bus now gone
  106. kDevNWakeup                        EQU        2                    ; Plug-in sw state no longer needs synchronization
  107. kDevNSleep                        EQU        3                    ; Ask to synchronize SOFTWARE state of plug-in
  108.                                                             ; ...used by PowerMgr, DriverReplacer, Soft Dev Eject
  109. kDevNBootComplete                EQU        4                    ; used by motherboard expert to inform DFM boot complete
  110. kDevNIOInitComplete                EQU        5                    ; I/O system initialize complete
  111. kDevNNumOfPredefinedEvtInUse    EQU        6
  112. kDevNHighestEvtInUse            EQU        5
  113. ;  enum for "signed" values
  114.  
  115. kDevNSoftEject                    EQU        $80000001            ; (kDevNRemoved | kDevNSoftRequestMask)
  116. ;
  117. ; ß
  118. ;########################################################################
  119. ;    Routine return value definition
  120. ;########################################################################
  121. ;
  122. ; typedef UInt32                         DevNPermissionResponse
  123.  
  124. ;  status returned by consumer to DevN
  125.  
  126. kDevNPermissionGranted            EQU        0                    ; consumer consented that instant removal of
  127.                                                             ; node is OK 
  128. kDevNPermissionDelayed            EQU        1                    ; can not grant permission now, will inform producer through .
  129.                                                             ; DevN at a later time (ignored by the DevN if hard request) 
  130. kDevNPermissionDenied            EQU        2                    ; do Not allow requested event to take place
  131.                                                             ;    (ignored by the DevN if hard request)
  132. kDevNValidPermissionMasks        EQU        3
  133. ;
  134. ;########################################################################
  135. ;    Error code definition
  136. ;########################################################################
  137. ;
  138.  
  139. kDevNMErrorCodeBase                EQU        0
  140. kInvalidSC                        EQU        1                    ; subscribe with invalid Service Category code
  141. kInvalidEvent                    EQU        2                    ; subscribe with invalid event mask (zero)
  142. kInvalidHandler                    EQU        3                    ; subscribe with NULL handler address
  143. kNoSuchRef                        EQU        4                    ; Specified ID can not be found
  144. kRecordNotFound                    EQU        5                    ; while unregistering, can not find record in array
  145. kNotEnoughEventMask                EQU        6                    ; not enough masks for DevNMCreateNewEvent call
  146. kDeleteInvalidMasks                EQU        7                    ; attempt to DevNMDeleteNewEvent on invalid event masks
  147. kInvalidEventCount                EQU        8                    ; invalid event count parameter being passed in
  148. kInvalidPermission                EQU        9                    ; bad permission returned from consumer
  149. kTokenNotFound                    EQU        10                    ; sub record lookup list token not found
  150. ;
  151. ;########################################################################
  152. ;    Subroutine Prototype
  153. ;########################################################################
  154. ; no more handlers
  155. ;######################                    
  156. ; called by consumer
  157. ;######################    
  158. ;
  159. ;
  160. ; extern OSStatus DevNRegisterInterestIn(OSType myFamily, ItemCount eventCount, DevNEventType *events, ObjectID adminMessageObj, DevNRef *thisRegistration, void *parm)
  161. ;
  162.     IF GENERATINGCFM THEN
  163.         IMPORT_CFM_FUNCTION DevNRegisterInterestIn
  164.     ENDIF
  165.  
  166. ;
  167. ; extern OSStatus DevNUnregisterInterest(DevNRef thisID)
  168. ;
  169.     IF GENERATINGCFM THEN
  170.         IMPORT_CFM_FUNCTION DevNUnregisterInterest
  171.     ENDIF
  172.  
  173. ;
  174. ; extern OSStatus DevNMCreateNewEvent(DevNEventType *result)
  175. ;
  176.     IF GENERATINGCFM THEN
  177.         IMPORT_CFM_FUNCTION DevNMCreateNewEvent
  178.     ENDIF
  179.  
  180. ;
  181. ; call to register family defined events.
  182. ; itemCount specifies how many events are desired
  183. ;    (Only create one event at a time)
  184. ;
  185. ;
  186. ; extern OSStatus DevNMDeleteNewEvent(DevNEventType event)
  187. ;
  188.     IF GENERATINGCFM THEN
  189.         IMPORT_CFM_FUNCTION DevNMDeleteNewEvent
  190.     ENDIF
  191.  
  192. ;  de-register the given event
  193. ;
  194. ; extern OSStatus DevNDelayedDownwardNotify(DevNRef notifyRef, DevNRef subscriptionRef, DevNPermissionResponse permission)
  195. ;
  196.     IF GENERATINGCFM THEN
  197.         IMPORT_CFM_FUNCTION DevNDelayedDownwardNotify
  198.     ENDIF
  199.  
  200. ;
  201. ; must be called after an kDevNPermissionDelayed is returned to the DevN
  202. ;    for a notification response.
  203. ;######################                    
  204. ; called by producer
  205. ;######################                    
  206. ;
  207. ;
  208. ; extern DevNPermissionResponse DevNNotifyThatThisChanged(OSType whichServiceCategory, DevNEventType whatHappened, RegEntryRef *whichDevice, ObjectID adminMessageObj, DevNRef *notRef, void *parm)
  209. ;
  210.     IF GENERATINGCFM THEN
  211.         IMPORT_CFM_FUNCTION DevNNotifyThatThisChanged
  212.     ENDIF
  213.  
  214. ;
  215. ; extern DevNPermissionResponse DevNNotifyEvents(DevNEventType whatHappened, RegEntryRef *whichDevice, ObjectID adminMessageObj, DevNRef *notRef, void *parm)
  216. ;
  217.     IF GENERATINGCFM THEN
  218.         IMPORT_CFM_FUNCTION DevNNotifyEvents
  219.     ENDIF
  220.  
  221. ;
  222. ;#####################################
  223. ; Notification Message definitions        
  224. ;#####################################
  225. ;
  226. DevNMessage                RECORD 0
  227. AdminMessageType         ds.l    1                ; offset: $0 (0)
  228. subMessageType             ds.l    1                ; offset: $4 (4)
  229. serviceCategory             ds.l    1                ; offset: $8 (8)
  230. event                     ds.l    1                ; offset: $C (12)
  231. device                     ds.l    1                ; offset: $10 (16)
  232. parm                     ds.l    1                ; offset: $14 (20)
  233. notRef                     ds.l    1                ; offset: $18 (24)
  234. returnPermission         ds.l    1                ; offset: $1C (28)
  235. sizeof                     EQU *                    ; size:   $20 (32)
  236.                         ENDR
  237. ;
  238. ;#########################################################
  239. ;    Device Notification sub-message types.    
  240. ;    (This is in the "subMessageType" field inside
  241. ;        The DevNMessage structure)
  242. ;#########################################################
  243. ;
  244.  
  245. kDevNNotifyMsg                    EQU        $01
  246. kDevNNotifyCancel                EQU        $02
  247. kDevNNotifyDelayedReply            EQU        $03
  248. kNextUnusedMsg                    EQU        $04
  249.     ENDIF
  250.     ENDIF ; __DEVICENOTIFY__ 
  251.  
  252.